fix: pin Readable.read() semantics to the compat matrix primary - #15

O problema

O PR #14 pinou o oráculo diferencial no primário da matriz e, com isso, expôs uma incoerência que já estava no runtime: ele era metade Node 24, metade Node 26.

A frente anterior (4edcb938) implementou a semântica do nodejs/node#60441 (semver-major, 26.0.0) nos três runtimes — mas sondou o node:stream local (26.8.1) antes de a doutrina do primário existir. O resultado ficou pela metade: o read() pausado devolvia chunk-a-chunk (26) enquanto o async-iterator concatenava (24); 2845/2846 vermelhas contra o oráculo primário; 1746/2813 fixando o pré-26.

Um binário compilado reproduz UM Node. Aplicando a doutrina que o #14 mergeou, este PR faz o runtime implementar a semântica do PRIMARY (24.15) de forma coerente em toda a superfície de streams, e deixa o ponto de mudança documentado para quando o primário for promovido a 26.

Sondagem: Node 24.15.0 vs 26.8.1

Matriz completa rodada nos dois binários reais (bare read pausado/fluindo, read(n), com/sem decoder, unshift depois de push e de read parcial, async-iterator). As duas majors divergem em UMA regra só, howMuchToRead(NaN):

Node 24:  state.flowing && state.length ? state.buffer.first().length : state.length
Node 26:  !state.decoder                ? state.buffer.first().length : state.length

Em 24 um read() pausado colapsa a fila inteira e só o modo flowing caminha chunk a chunk; em 26 um stream sem decoder devolve a entrada da cabeça nos dois modos.

Duas leituras importantes:

1. Tudo o que não é a regra do read() bate entre as majors — read(n), o read curto que espera o EOF, o read exato, objectMode, read(0), os data events em flowing, Readable.from, o produtor lento, e o caso com decoder (26 continua concatenando quando há StringDecoder).
2. A regra única se observa por três caminhos — o read() direto, o dreno num handler readable, e o async-iterator. É exatamente por isso que a divergência aparecia como "metade e metade": não eram três bugs, era um só, visível de três ângulos.

O que reverteu vs. o que manteve

Revertido (era semântica 26):

• packages/runtime/src/scr_stream.c — o gate flowing == 1 || !encoded dos dois pontos de howMuchToRead (antes e depois do refill) volta a flowing == 1.
• packages/runtime/src/island-js/13-stream.js — o read() sem argumento volta a colapsar a fila (_takeAll()). Ali read() é sempre o caminho pausado, porque flowing entrega por _drainData()/_takeChunk().
• packages/runtime-rust/src/readable.rs — o bare read volta a pedir available em vez do tamanho do chunk da cabeça (o head fica sem uso e sai).

Mantido (já batia com 24, confirmado nas sondas acima):

• read(n) curto que espera o EOF e só então libera o restante; e read(n) exatamente igual ao bufferizado, que colapsa a fila.
• read(NaN) tratado como a forma ausente.
• unshift — a ordem LIFO e a inserção na frente nunca estiveram erradas. O que fazia o unshift parecer vazado era o read() do outro lado.

Ponto único de mudança

Os três runtimes carregam agora, na própria expressão, as duas formas (24 e 26) e a nota de que read() segue NODE_COMPAT_MATRIX.primary, com o ponteiro para o nodejs#60441. Promover o primário a 26 é editar três expressões.

Como ainda não existe perfil de node:stream (só events/fetch/url, e o de fetch cobre Web Streams, não o Readable), o checklist de promoção ficou no cabeçalho de packages/compiler/src/compat/node-matrix.ts, numa seção nova — "Semantics the primary DECIDES (not just labels)". Ela nomeia a distinção que faltava: a maior parte da matriz é censo (um membro existe numa major e não na outra, e as duas respostas ficam gravadas), mas algumas linhas são de outra natureza — as duas majors dão respostas diferentes para a mesma chamada, e o binário só reproduz uma. Essas seguem o primário, e cada uma delas entra nessa lista para que uma promoção seja um checklist e não uma escavação.

Prova de que o runtime é coerentemente 24

A mesma lane npm sob o oráculo 26 fica vermelha em exatamente dois cenários, com o runtime emitindo as respostas do 24:

FAIL  npm differential (63 programs) > stream-shims
- paused-read: b:hel|b:lo |world      (esperado por Node 26)
+ paused-read: b:hel|b:lo world|null  (o que o runtime emite = Node 24)
- unshift: b:a                        (esperado por Node 26)
+ unshift: b:abc                      (o que o runtime emite = Node 24)

A divergência está confinada ao nodejs#60441 — nada mais na superfície de streams separa as duas majors.

Fixtures

2845/2846 reescritas contra a verdade do 24, cobrindo agora as duas metades da regra: o dreno pausado (que colapsa) e o flowing (que caminha), para que o gate não possa ser achatado nem para um lado nem para o outro. 1746/2813 seguem verdes sem toque.

Removi de 2845 o caso de read() com decoder: o compilador ainda não tem inspect lowering para Uint8Array | null (SC1090) e o runtime Rust lança em read() sobre stream com encoding. É o caso em que as duas majors concordam, então não carrega valor de pinagem — 1744-stream-set-encoding já o cobre.

Placar

Tudo rodado com o vitest sob o Node 24.15 pinado, com o PATH incluído — npm.test.ts spawna um node nu como oráculo, então a lane só está pinada se o PATH estiver.

Duas falhas fora do escopo — island static hello-world stays in its size class e surface-manifest every attestation-demoting libFn spelling is deniable by a manifest-id fence — já falham idênticas em origin/main, medido com o worktree limpo (stash) e rebuildado.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L4tTZUEZzWnw3rHKVQDTMn